{# Integration instructions template
 #
 # Copyright 2008-2009 Proven Corporation Co., Ltd., Thailand
 #
 # This file is part of App Engine Console.
 #
 # App Engine Console is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, version 3 of the License.
 #
 # App Engine Console is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 #
 # You should have received a copy of the GNU General Public License
 # along with App Engine Console; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 #}

{% extends "help.html" %}

{% block helpcontent %}
    <h3>Integrating With Your Application</h3>
    <p>
        App Engine Console's purpose in life is to provide a helpful mechanism to do application development
        from "within" the runtime.  Once you get a console tied to your own application, you can test ideas,
        create models and entities in the datastore, track down tough bugs, or do anything else that the
        engine allows.
    </p>

    <h4>Prerequisites</h4>
    <p>
        First, get a basic app engine application running on your system.  (See the
        <a href="http://code.google.com/appengine/docs/gettingstarted/">Getting Started guide</a> for instructions.)
    </p>
    <p>
        Next, ensure that your application does not already use the <tt>/console/</tt> path from within the site.
        To confirm this, start the development SDK normally and go to
        <a href="http://localhost:8080/console/">http://localhost:8080/console/</a>.
        You should get a 404 error (a blank page by default&mdash;so check your logs).  This is good
        because this is where the console interface will live.
    </p>
    <p>
        Finally, ensure that you do not already have a <tt>console</tt> subdirectory in your application code base,
        because that is where the code will live.
    </p>

    <h4>Installing The Code</h4>
    <p>
        Go to the <a href="{{project}}">App Engine Console project</a> page and download its zip file.
        Unpack this file in the topmost directory of your project (the one with your <tt>app.yaml</tt> in it).
        Everything will extract into one nice, clean subdirectory called <tt>console</tt>.
    </p>

    <h4>Enabling the Console</h4>
    <p>
        Edit your <tt>app.yaml</tt> file.  Insert two stanzas directly beneath the "handlers" line.
    </p>
    <div class="example">
        <pre>handlers:
- url: /console/static
  static_dir: console/app/view/static

- url: /console.*
  script: console/app/console.py

# (The rest of your handlers go below this line)
</pre>
    </div>

    <h4>Try It</h4>
    <p>
        Start the development SDK normally and go to <a href="http://localhost:8080/console/">http://localhost:8080/console/</a>.
        If you see the Python banner and a prompt then you are finished!  Poke around.  Create some entities.  Generate some log
        messages.  See the <a href="/console/help/usage">usage instructions</a> for more information.
    </p>

    <h4>Add Convenient Functions</h4>
    <p>
        As with the normal Python console, you need to import any modules, classes, etc. before you can use them.
        If you find yourself importing something often, consider adding it into the <tt>autoexec.py</tt>.  Every
        time a console session begins, it will first run <tt>from autoexec import *</tt>.
    </p>
    <p>
        For example, open <tt>autoexec.py</tt> and add the following code:
    </p>
    <div class="example pygments">{{example1}}</div>
    <p>
        Now you can use it easily at the console:
    </p>
    <div class="example pygments">{{example2}}</div>

    <h3>Configuration and Security</h3>
    <p>
        App Engine Console is great to use in production (i.e., hosted at appspot.com), because it provides a powerful way
        to inspect and manage datastore and memcache content.  However, before you deploy App Engine Console in production
        in your application, please go through the <tt>config.py</tt> file and make sure you are satisfied with these settings:
    </p>
    <table class="settings">
        <thead>
            <tr>
                <th>Variable</th>
                <th class="default">Default Value</th>
                <th class="desc">Description</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td class="variable">
                    hide_from_invalid_users
                </td>
                <td class="default">
                    False
                </td>
                <td class="desc">
                    When <tt>True</tt>, all console-related pages will return 404
                    (file not found) messages to unauthorized users.  This "cloak mode" makes it hard or impossible for normal users
                    to detect that the console is integrated with your site.
                </td>
            </tr>
            <tr>
                <td class="variable">
                    allow_any_user
                </td>
                <td class="default">
                    False
                </td>
                <td class="desc">
                    When <tt>True</tt>, any user can use the production
                    Python console once he has loggged in.  <em>(Not recommended)</em>
                </td>
            </tr>
            <tr>
                <td class="variable">
                    analytics_id
                </td>
                <td class="default">
                    ""
                </td>
                <td class="desc">
                    If you use Google Analytics, go to the dashboard for your site.  Check the
                    "id" value in the URL (<em>not "scid"</em>).  When you set <tt>analytics_id</tt> to that value, the Dashboard will then give you an easy
                    way to jump straight to your site's latest Google Analytics reports.
                </td>
            </tr>
            <tr>
                <td class="variable">
                    pastebin_subdomain
                </td>
                <td class="default">
                    ""
                </td>
                <td class="desc">
                    If this string is non-empty, the integrated pastebin window will
                    use that as a semi-private subdomain for the site.  This can be useful to avoid the clutter of other peoples' pasted material.
                </td>
            </tr>
            <tr>
                <td class="variable">
                    require_login_during_development
                </td>
                <td class="default">
                    False
                </td>
                <td class="desc">
                    When <tt>True</tt>, users must "log in" even when running
                    in development mode from the App Engine SDK.
                </td>
            </tr>
            <tr>
                <td class="variable">
                    python_doc_linking
                </td>
                <td class="default">
                    True
                </td>
                <td class="desc">
                    When <tt>True</tt>, many common modules, exceptions,
                    and types will be rendered as HTML links to the on-line Python documentation for those objects.
                </td>
            </tr>
            <tr>
                <td class="variable">
                    python_doc
                </td>
                <td class="default">
                    "http://docs.python.org/dev"
                </td>
                <td class="desc">
                    This URL is used as the base directory for
                    links to the Python documentation.  If you have your own copy of the documentation, you can set this to have the links go there instead.
                </td>
            </tr>
        </tbody>
    </table>
{% endblock %}
